This document lists/explains configuration and metadata for Sugar Cake (SCake) animations. Not all parameters are required, but filling them in is recommended.

: DISCLAIMER :
	Project Sugar Cake is incomplete, these are just the currently PLANNED systems and are not all currently in and functional. Please have patience as systems are integrated over time.

	This document makes the system 'look' really complex, but really to get an animation going you just need a single animation montage within UE5 and you can set up an animation event, however for the optimal experience you'll want at least 1 preclimax animation, 1 climax, and 1 postclimax animation. (If you lack any of these, you can just set the same animation for each stage)

[> Systems Explainer <]
	Project Sugar Cake features a highly customizable animation system for both animators and users with the goal of allowing animators to take advantage of the full animation montage system in UE5 while still integrating with the game and allowing users to customize and create their own animation events. To better understand the systems let's go over how SCake works. SCake uses what I call "Animation Events", these events consist of various individual animations stringed together in 'stages' with metadata both specific to each animation as well as the animation event as a whole. Each individual animation is registered into SCake, then Animation Events can be configured to use any animation. Animators are encouraged to create their own Animation Events that act as a full scene, but this is not required since users will be able to configure those animations into their own events as they desire. Players can also choose to manually play through Animation Events and select animations they like.

	'Paths' are critical to the dynamic systems of Animation Events. Erotic animations play through on 3 paths that are configured dynamically. The first path is the 'normal' path, this is the main animation's playtime without any climax. Non-Erotic animations will always use this first path exclusively and assume no climax. The second path is the climax path, this consists of animations both for climax animations with a limited number of climaxing actors as well as in-sync climax animations when all actors are at climax. If not all actors have climaxed after the animations on the second path has finished then it transitions back to the first path, but if all actors have climaxed then it transitions to the final path. This third path is a short post-climax animation used as a 'finishing touches' style animation. (Additionally what triggers this post-climax animation can be configured by the framework, such as entering only after all actors climax, or only after all included males climax, ect.)

	Path Examples with 2 actors...
		Standard Synced Climax Animation
		'PreClimax'	  : - - - - - - |
		'Actor1Climax':
		'Actor2Climax':
		'SyncedClimax':             | - |
		'Post Climax' :                 | - END
		
		Individual Climax Animation where Actor 2 orgasms first
		'PreClimax'	  : - - |   | - |
		'Actor1Climax':             | - |
		'Actor2Climax':     | - |
		'SyncedClimax':
		'Post Climax' :                 | - END
		
		Individual Climax Animation where Actor 1 orgasms but Actor 2 does not
		'PreClimax'	  : - - - - |   | - - - END
		'Actor1Climax':         | - |
		'Actor2Climax':
		'SyncedClimax':
		'Post Climax' :
		
		No Climax or Non-Erotic Animation
		'PreClimax'	  : - - - - - - - - - - END
		'Actor1Climax':
		'Actor2Climax':
		'SyncedClimax':
		'Post Climax' :

	These examples assume automatic (or at least linearly played) animations with a fixed end time, however users can change how events play out or choose to play individual animations with switching to climax animations automatically or by the user's input.

	All this sounds great, however not all animation packs will feature the full set of animations available, so some 'orgasm effects' may be applied instead depending on how each Animation Event is configured. Some strangeness can also occur if climax animations are not in sync with the animation it is transitioning from, such as switching from doggy style to missionary style, some care should be taken when configuring animations. Also, certain fetishes may not fit into this mold. In these cases where the system doesn't fit your needs you can create custom events using UE5 Anim Montages with SCake Module integration for the desired effect, animations can even store arbitrary string data to reference (This data is stored as a TMap|Name|String, use Name to reference).

[> Physical Gender/Sex Assignment <]
	For the sake of simplicity, 'Gender/Sex' definitions are entirely determined by the 'equipment' of the body and have nothing to do with identity. Currently (at the time of writing) the base game only supports Male and Female, however SCake defines bodies as having certain physical sex organs, such as vagina, penis, breasts, penis+vagina, anus, ect. Users will be able to configure what each Pal Type has so it can match their customized game properly.

[> Additional Notes <]
	- Proper initial configuration is important, if you're an animator and struggling to configure your animations please contact me or post over on our Discord for help and we can get things rolling! ^-^
	- Although the framework will support automatic sound configurations, custom sounds can be played through the Anim Montage system itself. (Call the SCake Event to play built-in animation sounds)
	- External objects (furniture) can be defined, but are not required.
	- 'Equips' (like toys) will be supported by the framework but can also be applied through Anim Montages and Modules

[> Limitations <]
	- Gender assignment is limited to male / female within the game, an additional framework would be required to change this and support more. Manual option to allow one to act as the other will be available.
	- If an Anim Montage has invalid metadata then it can't be registered for use in the framework. Most options will have defaults to fall back on but requirements must be filled.
	- If an Animation Event features an invalid animation it won't be registered or usable, all animations must have valid data and align with all animations in the event.
	- Animations can only be initially registered by path, this is because there's no way to ensure any other variables will initiate before registration. Within the UI users can still select by name, but these will only show after animations have been registered.

IMPORTANT NOTE :
	It is important to configure animations and these parameters correctly to provide users the best experience. It's worth learning some of UE5's animation montage features before you begin animating to better understand how these systems can be used.

User Configuration :
	Users will be able to change all animation configurations or even blend stages from different animations together to create their own animation events. This means if something isn't working correctly, this can be adjusted by the user.

-- -- --

[> Key-Terms <]
	SCake_
		Prefix applied to callable Sugar Cake functions, makes them easier to find in the BP system.
	Animation Event
		Animation Event refers to all Stages of a partiular event
	Stage
		Animations are divided into 'stages' where each stage has its own designated animation. Animators can define how each stage behaves and how long each stage is expected to last. By default stages progress linearly and automatically but users can choose to manually progress stages.
	Climax
		Climax refers to an orgasm animation.

-- -- --

[> Animation Parameters <]

	Notes :
		- When registering animations, register normal animations and then link climax animations. If you have multiple climax animations for a single normal animation you can register an animation with different climax variants and register it as a new animation with a new unique AnimID.
		- Currently there is no sound implementation for the framework, so sounds must be done manually through the Animation Montages themselves. In the future custom sound events and options may be added.

	~ Parameters for Animations ~

	UniqueAnimID
		[Required] Insert a unique ID to give your animations for calling inside AnimEvents (Conflicting names will overwrite one another, I recommend your author title + anim name)
	AnimName
		[Optional] Name for the animation
	AnimAuthor
		[Optional] Credit name of the animation creator
	AnimByPath
		[Required] Internal path to the Anim Montage file, required when registering via string/json, include all Actor Slots
	LinkClimaxAnims
		[Recommended] Links climax animations for auto-fill in stage configuration and manual animation playback, using AnimByPath is recommended to avoid name conflicts, climax animations must still be registered individually
	ActTypes
		[Recommended] Defines interaction/penetration types for each actor, assumes None if not included, define NonErotic for characters that shouldn't build pleasure/climax
	Compatibility
		[Required] Compatible combinations available by sex organ and species, species is required either by name via string or by class via reference for all Actor Slots
	Tags
		[Optional] Tags use to find, sort, and categorize animations
	NotErotic
		If true, animation is considered not erotic and doesn't trigger climax
	IsLooping
		If true, animation will loop for its intended duration, otherwise will only play once and progress to the next stage, for looping animations, please ensure the Anim Montage itself loops
	SpeedDefault
		[Optional] Default animation speed used in the order of actor slot (0 > 1 > 2 > ect)
	StartTime
		[Optional] Start time for the animations when it begins playing
	EndTime
		[Optional] End time for the animations before it transitions to the next animation
	Aggressors
		[Optional] Actors this animation considers aggressors by slot, with no aggressors or all aggressors the animations is considered consentual
	ObjectTarget
		[Optional] List of possible Furniture/Object the animation will play on with offsets
	EquipType
		[Optional] Objects to try and equip for animations
	SyncPosition
		[Optional] Use UE5 Slotted system to bind actors together (if off, uses a global position for all actors), best used with animations designed for it
	ActorAdjust
		[Optional] Adjusts actor positioning for this animation
	ArbString
		[Optional] Arbitrary string information, used to extend the framework functionality with modules
	AnimVersion
		[Optional] Version of the animation, when conflicts happen the highest version number overwrites lower values
	
	~ Parameters for Animation Events ~
	
	UniqueEventID
		[Required] Unique ID to give your Anim Event. Anim Events with the same ID will overwrite one another. (I recommend your Author Name + Event Name)
	EventName
		Name for the Animation Event
	EventAuthor
		Name of the Animation Event creator
	Addtags
		[Optional]  List of tags to add for the Animation Event, will already include tags from individual animations
	OverwriteClimax
		If true, overwrites any animation climax variant with the global one
	GlobalClimaxVar
		[Recommended] List of climax variant animations that will apply if the stage lacks one, or if OverwriteClimax is enabled
	HasPostClimax
		While true, enables the post-climax animation, otherwise the animation event ends after all actors have had a climax, skipping the post-climax animation
	PostClimaxReq
		[Optional] Sets a custom requirement for the post-climax animation stage/path
	Stages
		[Required] Reference Animations by Name for each stage in order (Array slot 0 is the first stage)
	PostClimaxStage
		[Optional] While IncludePostClimax is True, sets which stage is the Post-Climax Animation, if invalid then the last stage is used
	StageOrder
		[Optional] The order to play stages in, will play linearly if left empty, ignores post climax stage
	UniqueDuration
		[Optional] When set above 1.0, the Animation Event will ignore the framework's time duration settings and use this instead
	EventVersion
		[Optional] Version of the animation event, when conflicts happen the highest version number overwrites lower values
	
	~ Parameters for Stages ~
	
	StageName
		Name to give this stage
	AnimID
		Gets animation to play by the UniqueAnimID you set
	ClimaxVar
		[Optional] List of climax variant animations to override an animation's linked climax variants
	SpeedMod
		[Optional] Alters the animation playback speed
	DurationWeight
		[Optional] How much of the total time this animation should attempt to take up before the final climax animations, adjusts based on a percentage, non-looping animations ignore this setting
	StartTime
		[Optional] Start time for the animations when it begins playing
	EndTime
		[Optional] End time for the animations before it transitions to the next animation

	~ Parameters for Climax Links ~

	SlotsToClimax
		Slots expected to climax with this animation and where they should climax
	AnimByPath
		Slots and their associated animation paths
	IsLooping
		Whether the animation should be looping or not

	~ Parameters for Climax Vars ~

	SlotsToClimax
		Slots expected to climax with this animation and where they should climax
	AnimID
		The ID for the animation to play